home *** CD-ROM | disk | FTP | other *** search
/ EnigmA Amiga Run 1997 May / EnigmA AMIGA RUN 18 (1997)(G.R. Edizioni)(IT)[!][issue 1997-05][EAR-CD II].iso / softwareupdate / system / amigados / filefunctions / functions.doc < prev    next >
Text File  |  1996-10-10  |  11KB  |  360 lines
  1. 3    FILE FUNCTIONS - FUNCTIONS
  2.  
  3. 3.1  QUICK REFERENCE
  4.  
  5. Here is a complete list of all file functions described in this
  6. chapter:
  7.  
  8.   Function        Description                                   
  9.   ------------------------------------------------------------
  10.   CreateDir()     Creates a directory.
  11.   DeleteFile()    Deletes a specified file or directory.
  12.   Relabel()       Renames a specified volume.
  13.   Rename()        Renames a specified file or directory.
  14.   SetComment()    Adds a comment to a file or direcotry.
  15.   SetProtection() Alters the protection bits on a file or dir.
  16.   ------------------------------------------------------------
  17.  
  18.  
  19.  
  20. ---------------------------------------------------------------
  21.  
  22. CreateDir()
  23.  
  24. ROM library: "dos.library/CreateDir", (All versions)
  25. #include <clib/dos_protos.h>
  26.  
  27. Creates a directory and puts an exclusive lock on it.
  28.  
  29. Synopsis: lock = CreateDir( dir_name );
  30.  
  31.   lock:     (BPTR) If the directory could be created or there
  32.             already exist a direcoty with the specified name
  33.             a BPTR (BPCL pointer) is returned. If the directory
  34.             on the other hand could not be created NULL is
  35.             returned.
  36.             
  37.   dir_name: (STRPTR) Pointer to a text string which contains
  38.             the name of the new directory (including any
  39.             necessary path).
  40.  
  41. If you have successfully created a directory you must unlock it
  42. as soon as you do not need the lock any more!
  43.  
  44. Here is a simple example on how to use the CreateDir()
  45. function:
  46.  
  47.   /* A "BCPL" pointer to our directory lock: */
  48.   BPTR my_dir_lock;
  49.  
  50.   - - -
  51.  
  52.   /* Try to create a directory: */
  53.   my_dir_lock = CreateDir( "Ram:MyDirectory" );
  54.  
  55.   /* Check if we have successfully created */
  56.   /* the directory or not:                 */
  57.   if( my_dir_lock == NULL )
  58.   {
  59.     /* Problems! */
  60.     printf( "Could not create the directory!\n" );
  61.     exit( 20 );
  62.   }
  63.  
  64.   - - -
  65.   
  66.   /* When we do not need the directory lock */
  67.   /* any more we unlock it:                 */
  68.   UnLock( my_dir_lock );
  69.  
  70.  
  71. See also: Lock(), UnLock()
  72.  
  73. ---------------------------------------------------------------
  74.  
  75. DeleteFile()
  76.  
  77. ROM library: "dos.library/DeleteFile", (All versions)
  78. #include <clib/dos_protos.h>
  79.  
  80. Deletes a specified file or directory.
  81.  
  82. Synopsis: ok = DeleteFile( name );
  83.  
  84.   ok:     (LONG) If the file/directory could be deleted TRUE is
  85.           returned, else FALSE is returned (the file/directory
  86.           could not be deleted).
  87.             
  88.   name:   (STRPTR) Pointer to a text string which contains
  89.           the name (including any necessary path) of the file
  90.           or directory you want to delete.
  91.           
  92. Remember that you can only delete empty directories.
  93.  
  94. Here is a simple example on how to use the DeleteFile()
  95. function:
  96.  
  97.   /* A simple boolean variable: */
  98.   BOOL ok;
  99.  
  100.   /* Delete a file: */
  101.   ok = DeleteFile( "RAM:Unimportand.dat" );
  102.  
  103.   /* Could we delete the file? */
  104.   if( ok )
  105.     printf( "File deleted!\n" );
  106.   else
  107.     printf( "File could not be deleted!\n" );
  108.  
  109.  
  110. See also: Open(), CreateDir()
  111.  
  112. ---------------------------------------------------------------
  113.  
  114. Relabel()
  115.  
  116. ROM library: "dos.library/Relabel", (V36+)
  117. #include <clib/dos_protos.h>
  118.  
  119. Renames a specified volume.
  120.  
  121. Synopsis: ok = Relabel( old_name, new_name );
  122.  
  123.   ok:       (LONG) If the volume could be renamed TRUE is
  124.             returned, else FALSE is returned (the volume could
  125.             not be renamed).
  126.             
  127.   old_name: (STRPTR) Pointer to a text string which contains
  128.             the name of the volume you want to rename. Since
  129.             this is the current volume name you have to include
  130.             the colons ":" at the end of the volume name.
  131.             
  132.   new_name: (STRPTR) Pointer to a text string which contains
  133.             the new name of the volume. There should NOT be any
  134.             colons (:) at the end of this name since it is for
  135.             the moment not a volume name (but it will hopefully
  136.             soon be).
  137.           
  138. Note that this function was first included in dos library V36!
  139.  
  140. You can only rename volumes with this function. To rename a
  141. file or directory you have to use the "Rename()" function.
  142.  
  143. Here is a simple example on how to use the Relabel() function:
  144.  
  145.   /* A simple boolean variable: */
  146.   BOOL ok;
  147.  
  148.   /* Rename the device: (We will try to rename the volume */
  149.   /* "Programs:" to "SourceCode".)                        */
  150.   ok = Relabel( "Programs:", "SourceCode" );
  151.  
  152.   /* Could we rename the volume? */
  153.   if( ok )
  154.     printf( "The volume was successfully renamed!\n" );
  155.   else
  156.     printf( "The volume could not be renamed!\n" );
  157.  
  158.  
  159. See also: Rename()
  160.  
  161. ---------------------------------------------------------------
  162.  
  163. Rename()
  164.  
  165. ROM library: "dos.library/Rename", (All versions)
  166. #include <clib/dos_protos.h>
  167.  
  168. Renames a specified file or directory. It is possible to rename
  169. a file or directory so it is moved to another location on the
  170. same volume.
  171.  
  172. Synopsis: ok = Rename( old_name, new_name );
  173.  
  174.   ok:       (LONG) If the file/directory could be renamed TRUE
  175.             is returned, else FALSE is returned (the file/
  176.             directory could not be renamed).
  177.             
  178.   old_name: (STRPTR) Pointer to a text string which contains
  179.             the name (including any necessary path) of the file
  180.             or directory you want to rename.
  181.  
  182.   new_name: (STRPTR) Pointer to a text string which contains
  183.             the new name (including any necessary path) of the
  184.             file or directory. The path may be different as
  185.             long as it is still on the same volume.
  186.           
  187. Note, you can not rename a file or directory to another volume!
  188.  
  189. You can not rename a volume with this function. You must then
  190. instead use the new "Relabel()" function.
  191.  
  192. Here is a simple example on how to use the Rename() function:
  193.  
  194.   /* A simple boolean variable: */
  195.   BOOL ok;
  196.  
  197.   /* Rename a file: (We not only rename the actual file, but  */
  198.   /* we also move the file inside a directory called "MyDir") */
  199.   ok = Rename( "RAM:HorribleName.doc", "RAM:MyDir/Good.doc" );
  200.  
  201.   /* Could we rename the file? */
  202.   if( ok )
  203.     printf( "File renamed!\n" );
  204.   else
  205.     printf( "File could not be renamed!\n" );
  206.  
  207.  
  208. See also: Relabel()
  209.  
  210. ---------------------------------------------------------------
  211.  
  212. SetComment()
  213.  
  214. ROM library: "dos.library/SetComment", (All versions)
  215. #include <clib/dos_protos.h>
  216.  
  217. Adds a comment to a file or direcotry.
  218.  
  219. Synopsis: ok = SetComment( file_name, comment );
  220.  
  221.   ok:      (LONG) If the comment could be attached to the file
  222.            or directory TRUE is returned, else FALSE is
  223.            returned (the comment could not be attached).
  224.  
  225.   name:    (STRPTR) Pointer to a text string which contains
  226.            the name (including any necessary path) of the file
  227.            or directory you want to add the comment to.
  228.  
  229.   comment: (STRPTR) Pointer to a text string which contains
  230.            the comment you want to add. The comment can be up
  231.            to 80 characters long. (Any old comment will be
  232.            replaced.)
  233.  
  234. Here is a simple example on how to use the SetComment()
  235. function:
  236.  
  237.   /* A simple boolean variable: */
  238.   BOOL ok;
  239.  
  240.   /* Add a comment to the file: */
  241.   ok = SetComment( "Ram:Hello.c", "My wonderful program!" );
  242.  
  243.   /* Was the comment successfully added? */
  244.   if( ok )
  245.     printf( "The comment was successfully attached!\n" );
  246.   else
  247.     printf( "Error! Could not add the comment!\n" );
  248.  
  249.  
  250. See also: -
  251.  
  252. ---------------------------------------------------------------
  253.  
  254. SetProtection()
  255.  
  256. ROM library: "dos.library/SetProtection", (All versions)
  257. #include <clib/dos_protos.h>
  258.  
  259. Alters the protection bits on a file or directory.
  260.  
  261. Synopsis: ok = SetComment( file_name, flags );
  262.  
  263.   ok:     (LONG) If the protection bits could be altered as
  264.           instructed the function returns TRUE, else FALSE is
  265.           returned (the protection bits could not be altered).
  266.  
  267.   name:   (STRPTR) Pointer to a text string which contains
  268.           the name (including any necessary path) of the file
  269.           or directory which protection bits you want to
  270.           alter.
  271.  
  272.   flags:  (LONG) The protection bits you want to alter. You
  273.           set and/oor removes the bits with help of the
  274.           following flags: (defined in header file
  275.           "dos/dos.h")
  276.   
  277.             FIBF_DELETE:
  278.                  If this flag is set the "d" bit is removed so
  279.                  the file or directory can not be deleted. If
  280.                  this flag is not set the "d" bit will be
  281.                  added.
  282.                  
  283.             FIBF_EXECUTE:
  284.                  If this flag is set the "e" bit is removed so
  285.                  Shell (CLI) will refuse to start the file as a
  286.                  program. If this flag is not set the "e" bit
  287.                  will be added.
  288.  
  289.             FIBF_WRITE:
  290.                  If this flag is set the "w" bit is removed so
  291.                  no one can alter the file. If this flag is not
  292.                  set the "w" bit will be added.
  293.                  
  294.             FIBF_READ:
  295.                  If this flag is set the "r" bit is removed so
  296.                  no one can read the file. If this flag is not
  297.                  set the "r" bit will be added.
  298.                  
  299.  
  300.             FIBF_ARCHIVE:
  301.                  If this flag is set the "a" bit will be added
  302.                  which indicates that the file has been
  303.                  archived. If this flag is not set the "a" bit
  304.                  will be removed.
  305.  
  306.             FIBF_PURE:
  307.                  If this flag is set the "p" bit will be added
  308.                  which tells the Shell command "Resident" that
  309.                  this file is "pure" and can be made resident.
  310.                  If this flag is not set the "p" bit will be
  311.                  removed.
  312.  
  313.             FIBF_SCRIPT:
  314.                  If this flag is set the "s" bit will be added
  315.                  which tells Shell that this file is a script.
  316.                  If this flag is not set the "s" bit will be
  317.                  removed.
  318.  
  319.             Note that the first four flags will remove the
  320.             corresponding bits if the flags are set. The last
  321.             three flags will on the other hand set the
  322.             corresponding bits if the flags are set!
  323.  
  324.             To set sveral flags simply add a "|" sign between
  325.             them. So to protect a file from being accidentally
  326.             deleted and to instruct the Shell that it is a
  327.             script you set this field to:
  328.               FIBF_DELETE | FIBF_SCRIPT
  329.  
  330.             Note that the "e", "w" and "r" bits will also
  331.             be set and "a" and "p" removed!
  332.  
  333. Here is a simple example on how to use the SetProtection()
  334. function:
  335.  
  336.   /* A simple boolean variable: */
  337.   BOOL ok;
  338.  
  339.   /* Protect the file from being accidentally deleted */
  340.   /* and tell Shell it is a script:                   */
  341.   ok = SetProtection( "S:PrepCompiler",
  342.     FIBF_DELETE | FIBF_SCRIPT );
  343.  
  344.   /* Could we alter the protection bits as desired? */
  345.   if( ok )
  346.     printf( "The protection bits were successfully altered!\n" );
  347.   else
  348.     printf( "Error! Could not alter the protection bits!\n" );
  349.  
  350.  
  351. See also: -
  352.  
  353. ---------------------------------------------------------------
  354.  
  355.  
  356.  
  357.  
  358.  
  359.  
  360.